---
title: Docs Preview GitHub Action
description: How our composite GitHub Action deploys the docs preview to Vercel and posts a sticky PR comment.
---

Our repository includes a composite GitHub Action that:

- Deploys the documentation site to Vercel (staging or production based on
  branch and inputs)
- Posts or updates a sticky PR comment with a preview link
- Optionally posts a commit comment on push events
- Skips unnecessary deployments based on file changes or template changes, and
  explains why when it skips

## Where it lives

- Action entry: `internals/c15t-github-action/action.yml` (composite)
- Runtime code: `internals/c15t-github-action/src/main.ts` and `src/steps/*`

## When it runs

The workflow `.github/workflows/deploy-docs.yml` triggers on:

- push on `main` and `canary`
- pull\_request on any branch
- a nightly schedule (to check for upstream template changes)

## Inputs (selected)

- `GITHUB_TOKEN`: token used by the action (required)
- `setup_docs`: fetches the private docs template into `.docs` (default: true)
- `only_if_changed`: deploy only when relevant files have changed (default: false)
- `change_globs`: newline-separated globs of files that trigger deploy
- `check_template_changes`: also deploy when the upstream template changed
- `vercel_token`, `vercel_project_id`, `vercel_org_id`: credentials for Vercel
- `target`: `production` or `staging`
- `assign_alias_on_branch`: branch name to assign the alias on (e.g. `canary`)
- `alias_domains`: newline-separated alias domains to assign (supports `{{PR_NUMBER}}`, `{{BRANCH}}`)
- `comment_on_push`: also post a commit comment on push events (default: false)
- `skip_unchanged`: don't update sticky comment if body unchanged (default: false)
- `post_skip_comment`: when a deployment is skipped, post a skip comment on the
  PR (or a commit comment on push with `comment_on_push: true`)
- `skip_message`: optional override body for the skip comment
- `post_skip_comment`: when a deployment is skipped, post a skip comment on the
  PR (or a commit comment on push with `comment_on_push: true`)
- `skip_message`: optional override body for the skip comment

## Preview comment content

We render a consistent, branded Markdown comment using `render-comment.ts`:

- ASCII art header (with special first-contribution banner on your first PR)
- A preview table with status and timestamp
- Footer with attribution

When a deployment is skipped, we still post a comment indicating "Skipped" and show the last successful Vercel URL when available.

## How skipping works

- If `only_if_changed` is enabled, the action looks at changed paths and skips when none match `change_globs`.
- If `check_template_changes` is enabled, the action compares the latest upstream template commit against the last recorded deployment and may skip when they match.
- On skip, if `post_skip_comment` is `true`, the action posts a sticky comment
  (on PR) or a commit comment (on push with `comment_on_push: true`). You can
  override the body with `skip_message`.

## Local development

The action is executed using `tsx` directly (composite action), so no bundling step is required locally or in CI.

```yaml
runs:
  using: composite
  steps:
    - name: Run c15t action (tsx)
      shell: bash
      working-directory: ${{ github.action_path }}
      run: pnpm -w exec tsx "$GITHUB_ACTION_PATH/src/main.ts"
```

## Troubleshooting

- No comment on push: set `comment_on_push: "true"` in workflow inputs.
- No deploy on PR: ensure your changes match `change_globs` or disable `only_if_changed`.
- Node engine warning during docs setup: the `.docs` template may require a newer Node for dev tooling, but CI uses its own Node for the action. This warning can be ignored if the install continues.

## Related files

- `internals/c15t-github-action/src/steps/deployment.ts`
- `internals/c15t-github-action/src/steps/render-comment.ts`
- `internals/c15t-github-action/src/steps/comments.ts`
- `internals/c15t-github-action/src/steps/push-comment.ts`
